.TH std::allocator::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::allocator::allocate \- std::allocator::allocate

.SH Synopsis
   pointer allocate( size_type n, const void*          \fI(until C++17)\fP
   hint = 0 );
   T* allocate( std::size_t n, const void*             \fI(since C++17)\fP
   hint );                                             \fB(deprecated)\fP
                                               \fB(1)\fP     (removed in C++20)
   T* allocate( std::size_t n );                                          \fI(since C++17)\fP
                                                   \fB(2)\fP                    \fI(until C++20)\fP
   [[nodiscard]] constexpr T* allocate(                                   \fI(since C++20)\fP
   std::size_t n );

   Allocates n * sizeof(T) bytes of uninitialized storage by calling ::operator
   new(std::size_t)
   or ::operator new(std::size_t, std::align_val_t)
   \fI(since C++17)\fP, but it is unspecified when and how this function is called. The
   pointer hint may be used to provide locality of reference: the allocator, if
   supported by the implementation, will attempt to allocate the new memory block as
   close as possible to hint.

   Then, this function creates an array of type T[n] in the storage and starts its
   lifetime, but does not start lifetime of any of its elements.

   Use of this function is ill-formed if T is an incomplete type.

   In order to use this function in a constant expression, the allocated
   storage must be deallocated within the evaluation of the same          \fI(since C++20)\fP
   expression.

.SH Parameters

   n    - the number of objects to allocate storage for
   hint - pointer to a nearby memory location

.SH Return value

   Pointer to the first element of an array of n objects of type T whose elements have
   not been constructed yet.

.SH Exceptions

   Throws std::bad_array_new_length if                                    \fI(since C++11)\fP
   std::numeric_limits<std::size_t>::max() / sizeof(T) < n.

   Throws std::bad_alloc if allocation fails.

.SH Notes

   The "unspecified when and how" wording makes it possible to combine or optimize away
   heap allocations made by the standard library containers, even though such
   optimizations are disallowed for direct calls to ::operator new. For example, this
   is implemented by libc++ ([1] and [2]).

   After calling allocate() and before construction of elements, pointer arithmetic of
   T* is well-defined within the allocated array, but the behavior is undefined if
   elements are accessed.

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to      Behavior as published              Correct behavior
                       hint was required to be either
                       0 or a
   LWG 578  C++98      pointer previously returned     not required
                       from allocate()
                       and not yet passed to
                       deallocate()
   LWG 3190 C++11      allocate() might allocate       throws std::bad_array_new_length
                       storage of wrong size           instead

.SH See also

   allocate allocates uninitialized storage using the allocator
   \fB[static]\fP \fI(public static member function of std::allocator_traits<Alloc>)\fP
